Introduce constants for fetchLanguageName(s)

[lhc/web/wiklou.git] / languages / Language.php

diff --git a/languages/Language.php b/languages/Language.php
index 321d5f8..a6d320b 100644 (file)
--- a/languages/Language.php
+++ b/languages/Language.php
@@ -33,6 +33,25 @@ use CLDRPluralRuleParser\Evaluator;
  * @ingroup Language
  */
 class Language {
+       /**
+        * Return autonyms in fetchLanguageName(s).
+        * @since 1.32
+        */
+       const AS_AUTONYMS = null;
+
+       /**
+        * Return all known languages in fetchLanguageName(s).
+        * @since 1.32
+        */
+       const ALL = 'all';
+
+       /**
+        * Return in fetchLanguageName(s) only the languages for which we have at
+        * least some localisation.
+        * @since 1.32
+        */
+       const SUPPORTED = 'mwfile';
+
        /**
         * @var LanguageConverter
         */
@@ -790,16 +809,16 @@ class Language {
        /**
         * Get an array of language names, indexed by code.
         * @param null|string $inLanguage Code of language in which to return the names
-        *              Use null for autonyms (native names)
+        *              Use self::AS_AUTONYMS for autonyms (native names)
         * @param string $include One of:
-        *              'all' all available languages
+        *              self::ALL all available languages
         *              'mw' only if the language is defined in MediaWiki or wgExtraLanguageNames (default)
-        *              'mwfile' only if the language is in 'mw' *and* has a message file
+        *              self::SUPPORTED only if the language is in 'mw' *and* has a message file
         * @return array Language code => language name (sorted by key)
         * @since 1.20
         */
-       public static function fetchLanguageNames( $inLanguage = null, $include = 'mw' ) {
-               $cacheKey = $inLanguage === null ? 'null' : $inLanguage;
+       public static function fetchLanguageNames( $inLanguage = self::AS_AUTONYMS, $include = 'mw' ) {
+               $cacheKey = $inLanguage === self::AS_AUTONYMS ? 'null' : $inLanguage;
                $cacheKey .= ":$include";
                if ( self::$languageNameCache === null ) {
                        self::$languageNameCache = new HashBagOStuff( [ 'maxKeys' => 20 ] );
@@ -816,18 +835,21 @@ class Language {
        /**
         * Uncached helper for fetchLanguageNames
         * @param null|string $inLanguage Code of language in which to return the names
-        *              Use null for autonyms (native names)
+        *              Use self::AS_AUTONYMS for autonyms (native names)
         * @param string $include One of:
-        *              'all' all available languages
+        *              self::ALL all available languages
         *              'mw' only if the language is defined in MediaWiki or wgExtraLanguageNames (default)
-        *              'mwfile' only if the language is in 'mw' *and* has a message file
+        *              self::SUPPORTED only if the language is in 'mw' *and* has a message file
         * @return array Language code => language name (sorted by key)
         */
-       private static function fetchLanguageNamesUncached( $inLanguage = null, $include = 'mw' ) {
+       private static function fetchLanguageNamesUncached(
+               $inLanguage = self::AS_AUTONYMS,
+               $include = 'mw'
+       ) {
                global $wgExtraLanguageNames, $wgUsePigLatinVariant;
 
                // If passed an invalid language code to use, fallback to en
-               if ( $inLanguage !== null && !self::isValidCode( $inLanguage ) ) {
+               if ( $inLanguage !== self::AS_AUTONYMS && !self::isValidCode( $inLanguage ) ) {
                        $inLanguage = 'en';
                }
 
@@ -852,7 +874,7 @@ class Language {
                        }
                }
 
-               if ( $include === 'all' ) {
+               if ( $include === self::ALL ) {
                        ksort( $names );
                        return $names;
                }
@@ -863,7 +885,7 @@ class Language {
                        $returnMw[$coreCode] = $names[$coreCode];
                }
 
-               if ( $include === 'mwfile' ) {
+               if ( $include === self::SUPPORTED ) {
                        $namesMwFile = [];
                        # We do this using a foreach over the codes instead of a directory
                        # loop so that messages files in extensions will work correctly.
@@ -886,12 +908,17 @@ class Language {
 
        /**
         * @param string $code The code of the language for which to get the name
-        * @param null|string $inLanguage Code of language in which to return the name (null for autonyms)
-        * @param string $include 'all', 'mw' or 'mwfile'; see fetchLanguageNames()
+        * @param null|string $inLanguage Code of language in which to return the name
+        *   (SELF::AS_AUTONYMS for autonyms)
+        * @param string $include See fetchLanguageNames()
         * @return string Language name or empty
         * @since 1.20
         */
-       public static function fetchLanguageName( $code, $inLanguage = null, $include = 'all' ) {
+       public static function fetchLanguageName(
+               $code,
+               $inLanguage = self::AS_AUTONYMS,
+               $include = self::ALL
+       ) {
                $code = strtolower( $code );
                $array = self::fetchLanguageNames( $inLanguage, $include );
                return !array_key_exists( $code, $array ) ? '' : $array[$code];
@@ -2952,6 +2979,7 @@ class Language {
         * @deprecated No-op since 1.28
         */
        function initEncoding() {
+               wfDeprecated( __METHOD__, '1.28' );
                // No-op.
        }
 
@@ -2961,6 +2989,7 @@ class Language {
         * @deprecated No-op since 1.28
         */
        function recodeForEdit( $s ) {
+               wfDeprecated( __METHOD__, '1.28' );
                return $s;
        }
 
@@ -2970,6 +2999,7 @@ class Language {
         * @deprecated No-op since 1.28
         */
        function recodeInput( $s ) {
+               wfDeprecated( __METHOD__, '1.28' );
                return $s;
        }
 
@@ -3152,7 +3182,7 @@ class Language {
                        return;
                }
                $this->mMagicHookDone = true;
-               Hooks::run( 'LanguageGetMagic', [ &$this->mMagicExtensions, $this->getCode() ] );
+               Hooks::run( 'LanguageGetMagic', [ &$this->mMagicExtensions, $this->getCode() ], '1.16' );
        }
 
        /**
@@ -3208,7 +3238,7 @@ class Language {
                        $this->mExtendedSpecialPageAliases =
                                self::$dataCache->getItem( $this->mCode, 'specialPageAliases' );
                        Hooks::run( 'LanguageGetSpecialPageAliases',
-                               [ &$this->mExtendedSpecialPageAliases, $this->getCode() ] );
+                               [ &$this->mExtendedSpecialPageAliases, $this->getCode() ], '1.16' );
                }
 
                return $this->mExtendedSpecialPageAliases;
@@ -4321,13 +4351,18 @@ class Language {
         * the "raw" tag (-{R| }-) to prevent conversion.
         *
         * This function is called "markNoConversion" for historical
-        * reasons.
+        * reasons *BUT DIFFERS SIGNIFICANTLY* from
+        * LanguageConverter::markNoConversion(), with which it is easily
+        * confused.
         *
         * @param string $text Text to be used for external link
         * @param bool $noParse Wrap it without confirming it's a real URL first
         * @return string The tagged text
+        * @deprecated since 1.32, use LanguageConverter::markNoConversion()
+        *  instead.
         */
        public function markNoConversion( $text, $noParse = false ) {
+               wfDeprecated( __METHOD__, '1.32' );
                // Excluding protocal-relative URLs may avoid many false positives.
                if ( $noParse || preg_match( '/^(?:' . wfUrlProtocolsWithoutProtRel() . ')/', $text ) ) {
                        return $this->mConverter->markNoConversion( $text );